<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Getting started</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">
</head>
<body class="rustdoc">
    <!--[if lte IE 8]>
    <div class="warning">
        This old browser is unsupported and will most likely display funky
        things.
    </div>
    <![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
<div id='page'>


    <h1 class="title">Getting started</h1>
    <p>In this first chapter, you will install NWG and then look at a very simple application. This tutorial
        will use both <b>native-windows-derive</b> (the procedural macro to generate GUI's from rust structs) and the plain native-window-gui api.
        The next chapter "Basics" will go deeper into these.
    </p>
    <h1 id="installing-nwg" class="section-header"><a href="#installing-nwg">Installing NWG</a></h1>
    NWG should work with any recent version of rust (64 bits or 32 bits). Any channel can be used (stable, beta, nightly).
    NWG was mainly tested using the <b>MSVC ABI builds.</b> on both stable and nightly<br/>
    To use NWG in your project add it to <code>cargo.toml</code>:

<pre class="rust rust-example-rendered">[<span class="kw">dependencies</span>]
<span class="ident">native-windows-gui</span> = <span class="string"><span class="string">"</span>1.0.12<span class="string">"</span></span>
<span class="ident">native-windows-derive</span> = <span class="string"><span class="string">"</span>1.0.3<span class="string">"</span></span>
</pre>

    And then, in <code>main.rs</code> or <code>lib.rs</code> :

<pre class="rust rust-example-rendered">
<span class="kw">extern crate</span> <span class="ident">native_windows_gui</span> <span class="kw">as</span> <span class="ident">nwg</span>;
<span class="kw">extern crate</span> <span class="ident">native_windows_derive</span> <span class="kw">as</span> <span class="ident">nwd</span>;
</pre>

    <h1 id="hello-world" class="section-header"><a href="#hello-world">Hello World!</a></h1>
    Here is a minimalistic program that display a window with a text input and a button. When the button
    is clicked, a messagebox that says "Hello {your name}!" is created. This first example use <b>native-windows-derive</b>,
    scroll further down to see the plain API version.

<div class="highlight"><pre><span></span><span class="sd">/*!</span>
<span class="sd">    A very simple application that show your name in a message box.</span>
<span class="sd">    See `basic` for the version without the derive macro</span>
<span class="sd">*/</span><span class="w"></span>


<span class="k">extern</span><span class="w"> </span><span class="k">crate</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>
<span class="k">extern</span><span class="w"> </span><span class="k">crate</span><span class="w"> </span><span class="n">native_windows_derive</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwd</span><span class="p">;</span><span class="w"></span>

<span class="k">use</span><span class="w"> </span><span class="n">nwd</span>::<span class="n">NwgUi</span><span class="p">;</span><span class="w"></span>
<span class="k">use</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NativeUi</span><span class="p">;</span><span class="w"></span>


<span class="cp">#[derive(Default, NwgUi)]</span><span class="w"></span>
<span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_control(size: (300, 115), position: (300, 300), title: </span><span class="s">&quot;Basic example&quot;</span><span class="cp">, flags: </span><span class="s">&quot;WINDOW|VISIBLE&quot;</span><span class="cp">)]</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_events( OnWindowClose: [BasicApp::say_goodbye]</span><span class="w"> </span><span class="p">)]</span><span class="w"></span>
<span class="w">    </span><span class="n">window</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="cp">#[nwg_control(text: </span><span class="s">&quot;Heisenberg&quot;</span><span class="cp">, size: (280, 25), position: (10, 10))]</span><span class="w"></span>
<span class="w">    </span><span class="n">name_edit</span>: <span class="nc">nwg</span>::<span class="n">TextInput</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="cp">#[nwg_control(text: </span><span class="s">&quot;Say my name&quot;</span><span class="cp">, size: (280, 60), position: (10, 40))]</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_events( OnButtonClick: [BasicApp::say_hello]</span><span class="w"> </span><span class="p">)]</span><span class="w"></span>
<span class="w">    </span><span class="n">hello_button</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">impl</span><span class="w"> </span><span class="n">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>

<span class="w">    </span><span class="k">fn</span> <span class="nf">say_hello</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">simple_message</span><span class="p">(</span><span class="s">&quot;Hello&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">format</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;Hello {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">name_edit</span><span class="p">.</span><span class="n">text</span><span class="p">()));</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span>
<span class="w">    </span><span class="k">fn</span> <span class="nf">say_goodbye</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">simple_message</span><span class="p">(</span><span class="s">&quot;Goodbye&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">format</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;Goodbye {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">name_edit</span><span class="p">.</span><span class="n">text</span><span class="p">()));</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">stop_thread_dispatch</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>

<span class="p">}</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">init</span><span class="p">().</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to init Native Windows GUI&quot;</span><span class="p">);</span><span class="w"></span>

<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">_app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BasicApp</span>::<span class="n">build_ui</span><span class="p">(</span><span class="nb">Default</span>::<span class="n">default</span><span class="p">()).</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to build UI&quot;</span><span class="p">);</span><span class="w"></span>

<span class="w">    </span><span class="n">nwg</span>::<span class="n">dispatch_thread_events</span><span class="p">();</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>

    <h1 id="high-level-tutorial" class="section-header"><a href="#info-nwg">The example in details</a></h1>

    <h3>Basic project structure</h3>

    <b>Native-windows-gui</b> uses structures to represent a UI interface. Controls are represent as members. It's that simple.<br><br>
    
    Each control is a thin wrapper over a window handle (HWND). For more complex controls (such as listboxes), the control may contains extra data.
    All controls implements the <code>Default</code> trait. Default-built controls are considered <b>uninitialized</b>. Calling their methods
    will cause the program to panic.<br><br>

    Ui actions (displaying a message box in this case) should be implemented as structure methods. That is in no way a hard rule though.
    Any type of functions can be used. It just wraps nicely with the way the derive macro handles the events. 

    <h3>Native windows derive</h3>

    By deriving <code>NwgUi</code>, <b>Native-windows-derive</b> can automatically generate the Ui code. The derive macro has no way to actually know
    how to actually create the controls, so more information must be provided over the fields.<br><br>

    <code>nwg_control</code> specifies the control parameters. The actual syntax is <code>ident: expr</code>. The parameters names maps directly to
    the control builder field (yes NWG uses builders to create controls, more on that later). Check a specific control documentation to see which
    parameters are available.<br><br>

    In this example, <b>absolute positioning</b> is used. Ex: <code>position: (300, 300)</code>. This is ok for this example because the window
    cannot be resized, but NWG also supports layouts. <br><br>

    <code>nwg_events</code> specifies the events that the control responds to. It take an array of <code>EVENT_NAME: [callbacks]</code>. Note that
    this is only the default way to dispatch events. <b>nwg_events</b> can be further customized to match all your callback needs. Again, check
    a specific control documentation to see which events can be raised.<br><br>

    The derive macro has other functions that are out of scope for this introduction, see the native-windows-derive section for more information.

    <h3>Initialization</h3>

    Native windows GUI needs to initialize a few things before being usable. This includes styles and loading some control classes.
    The initialization done by calling <code>nwg::init()</code>. This function should not fail, but if it does, it's because the host system is really broken.
    In such case, the only thing left to do is to panic. Note that some helper functions (such as <code>nwg::simple_message</code>) can still be called.<br><br>

    The next thing to do is to initialize your application. As mentionned in the previous step, this means instantiating your struct.
    <b>native-windows-derive</b> implements the <code>NativeUi</code> trait, which gives you the <code>build_ui</code> function.
    The <code>build_ui</code> function takes a single argument: the initial state of your application (aka your UI struct default state).
    Because this application is very simple, there's no user state to initialize, so we just pass <code>Default::default</code> at 
    let native-windows-derive do its magic.<br><br>

    Finally, the only thing left is to start listening for events on the thread. This is done by calling <code> nwg::dispatch_thread_events()</code>.
    This function will block the thread until <code>nwg::stop_thread_dispatch()</code> is called. NWG does not provide a default handler on window close,
    so you will have to manually bind the `OnWindowClose` event<br><br>

    Now lets looks a the inner workings of NWG in the next section...
        

    <h1 id="hello-world" class="section-header"><a href="#hello-world2">Hello World! (no macro)</a></h1>
    Here is the same example without the macro.

<div class="highlight"><pre><span></span><span class="sd">/*!</span>
<span class="sd">    A very simple application that show your name in a message box.</span>
<span class="sd">    See `basic_d` for the derive version</span>
<span class="sd">*/</span><span class="w"></span>

<span class="k">extern</span><span class="w"> </span><span class="k">crate</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>
<span class="k">use</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NativeUi</span><span class="p">;</span><span class="w"></span>


<span class="cp">#[derive(Default)]</span><span class="w"></span>
<span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">window</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>
<span class="w">    </span><span class="n">name_edit</span>: <span class="nc">nwg</span>::<span class="n">TextInput</span><span class="p">,</span><span class="w"></span>
<span class="w">    </span><span class="n">hello_button</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">impl</span><span class="w"> </span><span class="n">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>

<span class="w">    </span><span class="k">fn</span> <span class="nf">say_hello</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">simple_message</span><span class="p">(</span><span class="s">&quot;Hello&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">format</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;Hello {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">name_edit</span><span class="p">.</span><span class="n">text</span><span class="p">()));</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span>
<span class="w">    </span><span class="k">fn</span> <span class="nf">say_goodbye</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">simple_message</span><span class="p">(</span><span class="s">&quot;Goodbye&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">format</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;Goodbye {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">name_edit</span><span class="p">.</span><span class="n">text</span><span class="p">()));</span><span class="w"></span>
<span class="w">        </span><span class="n">nwg</span>::<span class="n">stop_thread_dispatch</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>

<span class="p">}</span><span class="w"></span>

<span class="c1">//</span>
<span class="c1">// ALL of this stuff is handled by native-windows-derive</span>
<span class="c1">//</span>
<span class="k">mod</span> <span class="nn">basic_app_ui</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">native_windows_gui</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">nwg</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="k">super</span>::<span class="o">*</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">rc</span>::<span class="n">Rc</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">cell</span>::<span class="n">RefCell</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">ops</span>::<span class="n">Deref</span><span class="p">;</span><span class="w"></span>

<span class="w">    </span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">BasicAppUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">inner</span>: <span class="nc">Rc</span><span class="o">&lt;</span><span class="n">BasicApp</span><span class="o">&gt;</span><span class="p">,</span><span class="w"></span>
<span class="w">        </span><span class="n">default_handler</span>: <span class="nc">RefCell</span><span class="o">&lt;</span><span class="nb">Option</span><span class="o">&lt;</span><span class="n">nwg</span>::<span class="n">EventHandler</span><span class="o">&gt;&gt;</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>

<span class="w">    </span><span class="k">impl</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NativeUi</span><span class="o">&lt;</span><span class="n">BasicAppUi</span><span class="o">&gt;</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="k">fn</span> <span class="nf">build_ui</span><span class="p">(</span><span class="k">mut</span><span class="w"> </span><span class="n">data</span>: <span class="nc">BasicApp</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="nb">Result</span><span class="o">&lt;</span><span class="n">BasicAppUi</span><span class="p">,</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NwgError</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="k">use</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">Event</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">E</span><span class="p">;</span><span class="w"></span>
<span class="w">            </span>
<span class="w">            </span><span class="c1">// Controls</span>
<span class="w">            </span><span class="n">nwg</span>::<span class="n">Window</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">flags</span><span class="p">(</span><span class="n">nwg</span>::<span class="n">WindowFlags</span>::<span class="n">WINDOW</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">WindowFlags</span>::<span class="n">VISIBLE</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">size</span><span class="p">((</span><span class="mi">300</span><span class="p">,</span><span class="w"> </span><span class="mi">115</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">position</span><span class="p">((</span><span class="mi">300</span><span class="p">,</span><span class="w"> </span><span class="mi">300</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">title</span><span class="p">(</span><span class="s">&quot;Basic example&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">data</span><span class="p">.</span><span class="n">window</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>

<span class="w">            </span><span class="n">nwg</span>::<span class="n">TextInput</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">size</span><span class="p">((</span><span class="mi">280</span><span class="p">,</span><span class="w"> </span><span class="mi">25</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">position</span><span class="p">((</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">text</span><span class="p">(</span><span class="s">&quot;Heisenberg&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">parent</span><span class="p">(</span><span class="o">&amp;</span><span class="n">data</span><span class="p">.</span><span class="n">window</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">focus</span><span class="p">(</span><span class="kc">true</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">data</span><span class="p">.</span><span class="n">name_edit</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>

<span class="w">            </span><span class="n">nwg</span>::<span class="n">Button</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">size</span><span class="p">((</span><span class="mi">280</span><span class="p">,</span><span class="w"> </span><span class="mi">60</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">position</span><span class="p">((</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">40</span><span class="p">))</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">text</span><span class="p">(</span><span class="s">&quot;Say my name&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">parent</span><span class="p">(</span><span class="o">&amp;</span><span class="n">data</span><span class="p">.</span><span class="n">window</span><span class="p">)</span><span class="w"></span>
<span class="w">                </span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="n">data</span><span class="p">.</span><span class="n">hello_button</span><span class="p">)</span><span class="o">?</span><span class="p">;</span><span class="w"></span>

<span class="w">            </span><span class="c1">// Wrap-up</span>
<span class="w">            </span><span class="kd">let</span><span class="w"> </span><span class="n">ui</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BasicAppUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                </span><span class="n">inner</span>: <span class="nc">Rc</span>::<span class="n">new</span><span class="p">(</span><span class="n">data</span><span class="p">),</span><span class="w"></span>
<span class="w">                </span><span class="n">default_handler</span>: <span class="nb">Default</span>::<span class="n">default</span><span class="p">(),</span><span class="w"></span>
<span class="w">            </span><span class="p">};</span><span class="w"></span>

<span class="w">            </span><span class="c1">// Events</span>
<span class="w">            </span><span class="kd">let</span><span class="w"> </span><span class="n">evt_ui</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Rc</span>::<span class="n">downgrade</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ui</span><span class="p">.</span><span class="n">inner</span><span class="p">);</span><span class="w"></span>
<span class="w">            </span><span class="kd">let</span><span class="w"> </span><span class="n">handle_events</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">move</span><span class="w"> </span><span class="o">|</span><span class="n">evt</span><span class="p">,</span><span class="w"> </span><span class="n">_evt_data</span><span class="p">,</span><span class="w"> </span><span class="n">handle</span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                </span><span class="k">if</span><span class="w"> </span><span class="kd">let</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="n">ui</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">evt_ui</span><span class="p">.</span><span class="n">upgrade</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                    </span><span class="k">match</span><span class="w"> </span><span class="n">evt</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                        </span><span class="n">E</span>::<span class="n">OnButtonClick</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span>
<span class="w">                            </span><span class="k">if</span><span class="w"> </span><span class="o">&amp;</span><span class="n">handle</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ui</span><span class="p">.</span><span class="n">hello_button</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                                </span><span class="n">BasicApp</span>::<span class="n">say_hello</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ui</span><span class="p">);</span><span class="w"></span>
<span class="w">                            </span><span class="p">},</span><span class="w"></span>
<span class="w">                        </span><span class="n">E</span>::<span class="n">OnWindowClose</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span>
<span class="w">                            </span><span class="k">if</span><span class="w"> </span><span class="o">&amp;</span><span class="n">handle</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ui</span><span class="p">.</span><span class="n">window</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                                </span><span class="n">BasicApp</span>::<span class="n">say_goodbye</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ui</span><span class="p">);</span><span class="w"></span>
<span class="w">                            </span><span class="p">},</span><span class="w"></span>
<span class="w">                        </span><span class="n">_</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w">                    </span><span class="p">}</span><span class="w"></span>
<span class="w">                </span><span class="p">}</span><span class="w"></span>
<span class="w">            </span><span class="p">};</span><span class="w"></span>

<span class="w">           </span><span class="o">*</span><span class="n">ui</span><span class="p">.</span><span class="n">default_handler</span><span class="p">.</span><span class="n">borrow_mut</span><span class="p">()</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="n">nwg</span>::<span class="n">full_bind_event_handler</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ui</span><span class="p">.</span><span class="n">window</span><span class="p">.</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="n">handle_events</span><span class="p">));</span><span class="w"></span>

<span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="nb">Ok</span><span class="p">(</span><span class="n">ui</span><span class="p">);</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>

<span class="w">    </span><span class="k">impl</span><span class="w"> </span><span class="nb">Drop</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">BasicAppUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="sd">/// To make sure that everything is freed without issues, the default handler must be unbound.</span>
<span class="w">        </span><span class="k">fn</span> <span class="nf">drop</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="kd">let</span><span class="w"> </span><span class="n">handler</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">default_handler</span><span class="p">.</span><span class="n">borrow</span><span class="p">();</span><span class="w"></span>
<span class="w">            </span><span class="k">if</span><span class="w"> </span><span class="n">handler</span><span class="p">.</span><span class="n">is_some</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">                </span><span class="n">nwg</span>::<span class="n">unbind_event_handler</span><span class="p">(</span><span class="n">handler</span><span class="p">.</span><span class="n">as_ref</span><span class="p">().</span><span class="n">unwrap</span><span class="p">());</span><span class="w"></span>
<span class="w">            </span><span class="p">}</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>

<span class="w">    </span><span class="k">impl</span><span class="w"> </span><span class="n">Deref</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">BasicAppUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="k">type</span> <span class="nc">Target</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BasicApp</span><span class="p">;</span><span class="w"></span>

<span class="w">        </span><span class="k">fn</span> <span class="nf">deref</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">BasicApp</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="o">&amp;</span><span class="bp">self</span><span class="p">.</span><span class="n">inner</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">fn</span> <span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">init</span><span class="p">().</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to init Native Windows GUI&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">Font</span>::<span class="n">set_global_family</span><span class="p">(</span><span class="s">&quot;Segoe UI&quot;</span><span class="p">).</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to set default font&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">_ui</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BasicApp</span>::<span class="n">build_ui</span><span class="p">(</span><span class="nb">Default</span>::<span class="n">default</span><span class="p">()).</span><span class="n">expect</span><span class="p">(</span><span class="s">&quot;Failed to build UI&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="n">nwg</span>::<span class="n">dispatch_thread_events</span><span class="p">();</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
<br>
        

<h1 id="impl-tutorial" class="section-header"><a href="#info-nwg-2">The implementation in details</a></h1>

<h3>Native UI</h3>

Implementing NativeUI is the recommended way to create <b>native-windows-gui</b> application. This example is very close to what <b>native-windows-derive</b> outputs.

As mentioned in the previous section, all of the code logic is in <code>build_ui</code>.<br><br> For clarity, the method is separated in 3 steps: <b>Controls, Wrap-up, and Events</b>.

<h3>Controls</h3>

Native windows controls are built with builders. Each controls can instance a builder using the <code>nwg::CONTROL::builder()</code> method.
Default values and builder parameters are available in the documentation.<br><br>

The builder <code>build</code> function does not return the new control, instead you must pass a mutable reference to the function. This allows 
further customization of controls using <code>DerefMut</code> shenanigans.<br><br>

The control build can fail. End the builder call with a <code>?</code> to propagate the error to the caller. <br><br>

Regarding controls, <b>Native-windows-derive</b> includes a few features that improves quality of life.<br>
<ul>
    <li>It can guess the parent based on the order of the controls. Otherwise, you need to use the <code>parent</code> builder method.</li>
    <li>It unwraps the flags values. Going from <code>"WINDOW|VISIBLE"</code> to <code>nwg::WindowFlags::WINDOW | nwg::WindowFlags::VISIBLE</code></li>
</ul>


<h3>Wrap up</h3>

To keep things clean, a new structure called <code>[Control]Ui</code> wraps the inner application data.<br><br>

Before going further, the application data needs to be <b>Rc'ed</b>. This is because the application data needs to be shared between the events callbacks.<br><br>

This is the way of doing things is used because it is the <b>safest and simplest</b> way to handle callbacks. <br><br>

The ui wrapper also contains an handle to the default event handler. More on that in the next section.

<h3>Events</h3>

Okay. You might look at the way NWG handles events and tell yourself "wtf is this". Don't stress out. It might be different from how other
GUI platform handle events, but in the end, this way of doing things <b>wraps very nicely</b> with both Rust and the way events are dispatched in Windows.<br><br>

<code>full_bind_event_handler(parent_handle, callback)</code><br><br>

In Winapi, events hooking can be done by "subclassing" a window.
This is exactly what <code>full_bind_event_handler</code> do (with lots, lots of safety guards).
<br><br>

Every time an event is raised by the parent or it's children, the callback will be called. Behind the scene, NWG will carefully parse the raw winapi parameters
and return three simple values: an event <code>Event</code>, it's data (if any) <code>EventData</code>, and the sender window handle <code>ControlHandle</code>.<br><br>

You can see that there are no way to fetch our application data from these parameters. That's why the application data (now behind a RC) 
<b>is cloned and passed to the closure</b>. A <code>WeakRef</code> is used here so that <code>Drop</code> can be called.<br><br>

Inside the callback, the developer needs to do three things:
<ul>
    <li>Match the event value. <code>match evt</code></li>
    <li>Check which control sent the event. <code>&handle == &evt_ui.hello_button</code></li>
    <li>Call the required functions</li> <code>BasicApp::say_hello(&evt_ui.inner);</code>
</ul> <br>

Note that <code>full_bind_event_handler</code> applies to the parent and <b>all its children</b>. This means you only need to bind handlers on <b>TOP LEVEL window</b>.

Lastly, the handler returned by <code>full_bind_event_handler</code> is saved in the wrapper struct under <code>default_handler</code>.

<h3>Freeing</h3>

Events handlers are not automatically unbound on drop. it must be done using <code>nwg::unbind_event_handler(&handler)</code><br><br>

Because we use a <code>WeakRef</code> in our event handler, the ui struct only has 1 strong refcount. This way we can unbind the event handler in
the drop method.

<br><br>
And that is all for events handling. Thankfully, <b>native-windows-derive</b> handles all of this for us!


<h3>End note</h3>

Right now, you've learned about 50% of NWG. That's enough to build small applications, but there's two intermediate topics that you will want to learn: 
<b>layouts, and resources handling (fonts, image)</b>. For larger applications you will want to look at more advanced topics such as
<b>UI partials, dynamic control creation, dynamic event binding (and unbinding), and multithreading</b>.<br><br>

Good luck with your UI projects. Hopefully, NWG will be a good fit.


<br>
<br>
</div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
